Skip to content

Android: never expire a request - #93

Open
dmurphy5 wants to merge 3 commits into
dylan/android-network-wakefrom
dylan/android-no-deadlines
Open

dmurphy5 wants to merge 3 commits into
dylan/android-network-wakefrom
dylan/android-no-deadlines

Conversation

@dmurphy5

@dmurphy5 dmurphy5 commented Nov 18, 2026 •

Copy link
Copy Markdown

This must ship in the same release as #92 and the iOS removal.

The README and the type docs change in #92, "Contract: a request has no deadline; expiresAt and lifetimeMs are deprecated and ignored" (#92). This PR leaves them as they are, so the two do not conflict.

What was wrong

Android ran a timer on every request. When a request's expiresAt passed, the library settled it error with errorKind: 'expired', also when the server was only down for a while. That is a cancel() the library made on its own, and it works against the main goal: every request started on the device reaches the server.

The one app that uses the library does not need it: it sets a 10-year lifetime and queues again what expires.

The timer also caused defects. A parked (awaiting-auth) entry got a WorkManager wake at its expiresAt when that was less than 24 hours away. Each wake holds one of the app's 20 JobScheduler slots until it runs, so many parked entries could keep other uploads from starting.

What changes

  • No expiry check before an attempt, in a chunked part, or at a network poll.
  • A backoff waits its full time. Before, the in-worker wait, the long release and the release after a time-limit stop were cut at expiresAt.
  • A parked entry gets no WorkManager row. It waits for updateHeaders() or a same-id mutate(). The boot sweep cancels a wake that an earlier version left for it.
  • Native accepts a descriptor with or without expiresAt, and configure() with or without lifetimeMs, and ignores both.
  • entry.json keeps the expiresAt field. 11.0.2 to 11.3.0 read it as the deadline, and read a missing one as 0, which is already past. So a new entry, and an entry queued again by a same-id mutate(), stores Long.MAX_VALUE. An app that goes back to one of those versions does not expire it, and those versions do no sum with the field that overflows. An entry from an earlier version that is not queued again keeps its value. Nothing reads it.
  • The boot snapshot keeps delayedPastHorizon with the same 24-hour line, now a constant of its own. The app reads it as a sign of a stuck queue.

android/src/main: 53 lines added, 94 removed.

flowchart LR
  A[401 or 403] --> P[awaiting-auth]
  P -- before --> W[wake row at expiresAt] --> X[settle expired]
  P -- now --> N[no row] --> H[updateHeaders or same-id mutate] --> Q[queued, sent]
Loading

Behavior change

  • Android never settles a new outcome expired. A request retries until the server accepts it, a response or a missing file settles it as an error, or the app calls cancel(id).
  • A 5xx, 408, 429 or network failure now retries with no end: these have no retry count, and the deadline was their only limit. Each wait is bounded: at most 2 hours by default, 15 minutes after a failure where no server answered.
  • Two in-worker waits have no time bound. One is the network poll in the cases below. The other is a foreground run that retries in place when an app sets maxMs to 30 s or less. Both existed before with a far deadline: a 10-year lifetime never ended them.
  • An app that needs a limit calls cancel(id) itself.
  • Entries that an earlier version queued are sent, also when their expiresAt has passed.
  • An expired outcome that an earlier version stored and the app has not acknowledged is still delivered, unchanged.

What it does not change

  • iOS. It still expires requests until the iOS removal lands.
  • JS, the README and the type docs. JS still sets expiresAt and validates lifetimeMs. Contract: a request has no deadline; expiresAt and lifetimeMs are deprecated and ignored #92 changes all three.
  • The other ways an entry settles: a terminal HTTP status, a transient rule past its maxRetries, a missing file, an unknown error, and cancel().
  • How a run waits for the network. With foreground mode on Android 11 to 14 (or an app that targets below Android 15), and on Android 10, a run polls for the network for as long as it runs. A pause, cancel, replace or system stop also ends it.

Tests

Tests that asserted expiry are rewritten to assert the new rule. The new and rewritten tests:

  • An entry with expiresAt in the past is sent, simple and chunked.
  • A network wait that passes expiresAt keeps polling, then sends.
  • A transient failure past expiresAt retries on the normal backoff, in the worker (1 s, then 2 s) and on a long release (the full 60 s).
  • A time-limit stop past expiresAt releases to the full next backoff step.
  • A paused entry past expiresAt is sent at resume.
  • A 401 parks the entry and makes no WorkManager row. A wake an earlier version left finds it parked and does nothing. updateHeaders() then sends it.
  • 250 parked entries and 250 doorbell waiters with expiresAt 12 hours away leave 1 unfinished WorkManager row in all: the network doorbell. The test counts the rows after a second boot sweep, which runs once every expiresAt has passed.
  • An entry an earlier version saved with expiresAt in the past loads after a relaunch and is scheduled.
  • A new entry writes "expiresAt":9223372036854775807, and it reads back exact. A same-body re-queue of an entry whose expiresAt is 5 stores the same value.
  • A stored expired outcome from an earlier version is delivered unchanged.
  • A descriptor parses with expiresAt missing, 0, negative, in the past, a string, or null.

Mutation checks. Each one puts an expiry behaviour back in a scratch copy and runs the full suite. Every one makes a test fail:

Behaviour put back Tests that fail
Simple transfer settles expired before an attempt 4
Chunked part settles expired 1
Network poll ends at expiresAt 6
In-worker backoff cut at expiresAt 1
Long release cut at expiresAt 1
Release after a time-limit stop cut at expiresAt 1
Park makes an expiry wake 2
Boot sweep makes a parked entry's expiry wake 3 (the 250-entry test among them)
A wake settles a parked entry expired 1
Parsing requires expiresAt 1
Boot sweep skips an old entry past expiresAt 2
New entries store 0 as expiresAt 2
Boot sweep drops a stored expired outcome 1

Local checks on the tip commit, by exit code:

  • ./gradlew --no-daemon :react-native-background-upload:testDebugUnitTest: exit 0, 607 tests, 0 failures (600 on the base branch).
  • yarn test: exit 0, 305 tests.
  • yarn typecheck: exit 0.
  • yarn lint:ci: exit 0.

Review

An independent review agent read all 26 files, put each removed behaviour back in a scratch copy (each one made a test fail), and checked every use of the stored field in 11.0.2 to 11.3.0 for the downgrade case. Verdict: no blocker. Its four low items are fixed in the last commit.

🤖 Generated with Claude Code

dmurphy5 and others added 3 commits November 18, 2026 16:15
The library no longer settles an entry 'expired'. It ignores the
descriptor's expiresAt and configure()'s lifetimeMs. Removed: the expiry
checks before an attempt, at each network poll and in each chunked part;
the cap of in-worker backoffs, long releases and timeout releases at
expiresAt; and the expiry wake of a parked entry at park, in the boot
sweep and in the repair. A parked entry now gets no WorkManager row, and
the sweep cancels a wake an earlier version left for it.

New entries store expiresAt = Long.MAX_VALUE, so 11.3.0, which reads the
field as a deadline, does not expire them after a downgrade. Entries from
earlier versions keep their value and are sent. A stored 'expired'
outcome is still delivered.

The boot snapshot keeps delayedPastHorizon, now with its own 24-hour
constant.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…the contract PR

A same-body mutate() now writes expiresAt = Long.MAX_VALUE too, so an
entry from 11.3.0 that is queued again here does not expire after a
downgrade. The comment names the versions this is checked for: 11.0.2
to 11.3.0.

README.md and the doc comments in src/ go back to the base branch. The
contract PR rewrites the same sentences, and its text is the end state.
The CHANGELOG entry now speaks of the native module only.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@dmurphy5
dmurphy5 added this pull request to stack #89 November 18, 2026 21:54
@dmurphy5 dmurphy5 changed the title dylan/android no deadlines Android: never expire a request Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant